Ein detaillierter Vergleich von setup.py und pyproject.toml für das Python-Paketmanagement, mit Best Practices, Migrationsstrategien und modernen Werkzeugen.
Python Package-Struktur: Setup.py vs. Pyproject.toml – Eine umfassende Anleitung
Jahrelang war die Datei setup.py der Eckpfeiler des Python-Paketmanagements. Allerdings hat sich die Landschaft weiterentwickelt, und pyproject.toml hat sich als moderne Alternative herauskristallisiert. Diese umfassende Anleitung untersucht die Unterschiede zwischen diesen beiden Ansätzen und hilft Ihnen zu verstehen, welcher für Ihr Projekt der richtige ist und wie Sie Ihre Python-Pakete effektiv verwalten können.
Grundlagen verstehen
Was ist ein Python-Paket?
Ein Python-Paket ist eine Möglichkeit, Ihren Python-Code zu organisieren und zu verteilen. Es ermöglicht Ihnen, verwandte Module in einer Verzeichnisstruktur zu gruppieren, wodurch Ihr Code modularer, wiederverwendbarer und wartungsfreundlicher wird. Pakete sind unerlässlich, um Ihren Code mit anderen zu teilen und Abhängigkeiten in Ihren Projekten zu verwalten.
Die Rolle der Paketmetadaten
Paketmetadaten liefern wesentliche Informationen über Ihr Paket, wie z. B. seinen Namen, seine Version, den Autor, die Abhängigkeiten und die Einstiegspunkte. Diese Metadaten werden von Paketmanagern wie pip verwendet, um Ihre Pakete zu installieren, zu aktualisieren und zu verwalten. In der Vergangenheit war setup.py der primäre Weg, diese Metadaten zu definieren.
Setup.py: Der traditionelle Ansatz
Was ist Setup.py?
setup.py ist ein Python-Skript, das die Bibliothek setuptools verwendet, um die Struktur und die Metadaten Ihres Pakets zu definieren. Es handelt sich um eine dynamisch ausgeführte Datei, was bedeutet, dass sie Python-Code ausführt, um das Paket zu konfigurieren.
Hauptkomponenten von Setup.py
Eine typische setup.py-Datei enthält die folgenden Komponenten:
- Paketname: Der Name Ihres Pakets (z. B.
my_package). - Version: Die Versionsnummer Ihres Pakets (z. B.
1.0.0). - Autor- und Maintainer-Informationen: Details zum Autor und Maintainer des Pakets.
- Abhängigkeiten: Eine Liste anderer Pakete, von denen Ihr Paket abhängt (z. B.
requests >= 2.20.0). - Einstiegspunkte: Definitionen für Befehlszeilenskripte oder andere Einstiegspunkte in Ihr Paket.
- Paketdaten: Nicht-Code-Dateien (z. B. Konfigurationsdateien, Datendateien), die in das Paket aufgenommen werden sollen.
Beispiel Setup.py
```python from setuptools import setup, find_packages setup( name='my_package', version='1.0.0', author='John Doe', author_email='john.doe@example.com', description='A simple Python package', packages=find_packages(), install_requires=[ 'requests >= 2.20.0', ], entry_points={ 'console_scripts': [ 'my_script = my_package.module:main', ], }, classifiers=[ 'Programming Language :: Python :: 3', 'License :: OSI Approved :: MIT License', 'Operating System :: OS Independent', ], ) ```Vorteile von Setup.py
- Vertrautheit: Es ist der traditionelle und bekannte Ansatz, daher sind viele Entwickler bereits damit vertraut.
- Flexibilität: Da es sich um ein Python-Skript handelt, bietet es ein hohes Maß an Flexibilität. Sie können komplexe Logik ausführen und den Build-Prozess nach Bedarf anpassen.
- Erweiterbarkeit: Setuptools bietet eine umfangreiche Reihe von Funktionen und kann mit benutzerdefinierten Befehlen und Erweiterungen erweitert werden.
Nachteile von Setup.py
- Dynamische Ausführung: Die dynamische Natur von
setup.pykann ein Sicherheitsrisiko darstellen, da sie während des Build-Prozesses beliebigen Code ausführt. - Implizite Abhängigkeiten:
setup.pystützt sich häufig auf implizite Abhängigkeiten, wie z. B. Setuptools selbst, was zu Inkonsistenzen und Fehlern führen kann. - Komplexität: Für komplexe Projekte kann
setup.pygroß und schwer zu warten werden. - Begrenzte deklarative Konfiguration: Ein Großteil der Paketmetadaten wird eher imperativ als deklarativ definiert, was es schwieriger macht, darüber zu argumentieren.
Pyproject.toml: Die moderne Alternative
Was ist Pyproject.toml?
pyproject.toml ist eine Konfigurationsdatei, die das TOML-Format (Tom's Obvious, Minimal Language) verwendet, um das Build-System und die Metadaten Ihres Pakets zu definieren. Es ist ein deklarativer Ansatz, was bedeutet, dass Sie angeben, was Sie erreichen möchten, anstatt wie Sie es erreichen möchten.
Hauptabschnitte von Pyproject.toml
Eine typische pyproject.toml-Datei enthält die folgenden Abschnitte:
[build-system]: Definiert das zu verwendende Build-System (z. B.setuptools,poetry,flit).[project]: Enthält Metadaten über das Projekt, wie z. B. seinen Namen, seine Version, Beschreibung, Autoren und Abhängigkeiten.[tool.poetry]oder[tool.flit]: Abschnitte für toolspezifische Konfigurationen (z. B. Poetry, Flit).
Beispiel Pyproject.toml (mit Setuptools)
```toml [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = [ { name = "John Doe", email = "john.doe@example.com" } ] dependencies = [ "requests >= 2.20.0", ] [project.scripts] my_script = "my_package.module:main" [project.optional-dependencies] dev = [ "pytest", "flake8", ] [project.classifiers] classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ] [project.urls] homepage = "https://example.com" repository = "https://github.com/example/my_package" ```Beispiel Pyproject.toml (mit Poetry)
```toml [tool.poetry] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = ["John DoeVorteile von Pyproject.toml
- Deklarative Konfiguration:
pyproject.tomlbietet eine deklarative Möglichkeit, Ihre Paketmetadaten zu definieren, wodurch sie leichter verständlich und wartbar sind. - Standardisiertes Build-System: Es gibt das zu verwendende Build-System an und gewährleistet so konsistente Builds in verschiedenen Umgebungen.
- Verbessertes Abhängigkeitsmanagement: Tools wie Poetry und Pipenv lassen sich nahtlos in
pyproject.tomlintegrieren, um robuste Funktionen zur Abhängigkeitsverwaltung bereitzustellen. - Reduzierte Sicherheitsrisiken: Da es sich um eine statische Konfigurationsdatei handelt, beseitigt sie die Sicherheitsrisiken, die mit der dynamischen Ausführung von Code während des Build-Prozesses verbunden sind.
- Integration mit modernen Tools:
pyproject.tomlist der Standard für moderne Python-Paketierungstools wie Poetry, Pipenv und Flit.
Nachteile von Pyproject.toml
- Lernkurve: Entwickler müssen möglicherweise eine neue Syntax (TOML) und eine neue Art des Denkens über das Paketmanagement erlernen.
- Begrenzte Flexibilität: Es ist möglicherweise nicht für hochgradig angepasste Build-Prozesse geeignet, die komplexe Logik erfordern.
- Tooling-Abhängigkeit: Sie müssen ein bestimmtes Build-System (z. B. Setuptools, Poetry, Flit) auswählen und dessen Verwendung erlernen.
Vergleich von Setup.py und Pyproject.toml
Hier ist eine Tabelle, die die wichtigsten Unterschiede zwischen setup.py und pyproject.toml zusammenfasst:
| Merkmal | Setup.py | Pyproject.toml |
|---|---|---|
| Konfigurationsstil | Imperativ (Python-Code) | Deklarativ (TOML) |
| Build-System | Implizit (Setuptools) | Explizit (angegeben in [build-system]) |
| Sicherheit | Potenziell weniger sicher (dynamische Ausführung) | Sicherer (statische Konfiguration) |
| Abhängigkeitsmanagement | Grundlegend (install_requires) |
Erweitert (Integration mit Poetry, Pipenv) |
| Tooling | Traditionell (Setuptools) | Modern (Poetry, Pipenv, Flit) |
| Flexibilität | Hoch | Moderat |
| Komplexität | Kann für komplexe Projekte hoch sein | Im Allgemeinen niedriger |
Migrationsstrategien: Von Setup.py zu Pyproject.toml
Die Migration von setup.py zu pyproject.toml kann entmutigend erscheinen, aber es ist eine lohnende Investition für langfristige Wartbarkeit und Konsistenz. Hier sind einige Strategien, die Sie verwenden können:
1. Beginnen Sie mit einem minimalen Pyproject.toml
Erstellen Sie eine einfache pyproject.toml-Datei, die das Build-System angibt, und migrieren Sie dann schrittweise die Metadaten von setup.py nach pyproject.toml.
2. Verwenden Sie Setuptools mit Pyproject.toml
Verwenden Sie weiterhin Setuptools als Ihr Build-System, definieren Sie aber die Projektmetadaten in pyproject.toml. Auf diese Weise können Sie die Vorteile von pyproject.toml nutzen und gleichzeitig ein vertrautes Tool verwenden.
3. Migrieren Sie zu einem modernen Tool wie Poetry
Erwägen Sie die Migration zu einem modernen Tool wie Poetry oder Pipenv. Diese Tools bieten umfassende Funktionen zur Abhängigkeitsverwaltung und lassen sich nahtlos in pyproject.toml integrieren.
Beispiel: Migration zu Poetry
- Installieren Sie Poetry:
pip install poetry - Initialisieren Sie Poetry in Ihrem Projekt:
poetry init(Dies führt Sie durch das Erstellen einerpyproject.toml-Datei) - Fügen Sie Ihre Abhängigkeiten hinzu:
poetry add requests(oder andere Abhängigkeiten) - Erstellen Sie Ihr Paket:
poetry build
4. Verwenden Sie Tools für die automatisierte Migration
Einige Tools können den Migrationsprozess automatisieren. Sie können beispielsweise Tools verwenden, um Ihre setup.py-Datei in eine pyproject.toml-Datei zu konvertieren.
Best Practices für das Python-Paketmanagement
1. Verwenden Sie eine virtuelle Umgebung
Verwenden Sie immer eine virtuelle Umgebung, um die Abhängigkeiten Ihres Projekts von der systemweiten Python-Installation zu isolieren. Dies verhindert Konflikte und stellt sicher, dass Ihr Projekt die richtigen Abhängigkeiten hat.
Beispiel mit venv:
Beispiel mit conda:
2. Geben Sie Abhängigkeiten genau an
Verwenden Sie Versionsbeschränkungen, um die kompatiblen Versionen Ihrer Abhängigkeiten anzugeben. Dies verhindert unerwartetes Verhalten, das durch inkompatible Bibliotheksaktualisierungen verursacht wird. Verwenden Sie Tools wie pip-tools zur Verwaltung Ihrer Abhängigkeiten.
Beispiel für die Abhängigkeitsspezifikation:
``` requests >= 2.20.0, < 3.0.0 ```3. Verwenden Sie ein konsistentes Build-System
Wählen Sie ein Build-System (z. B. Setuptools, Poetry, Flit) und halten Sie sich daran. Dies gewährleistet konsistente Builds in verschiedenen Umgebungen und vereinfacht den Paketierungsprozess.
4. Dokumentieren Sie Ihr Paket
Schreiben Sie eine klare und präzise Dokumentation für Ihr Paket. Dies hilft Benutzern zu verstehen, wie sie Ihr Paket verwenden können, und erleichtert es anderen, zu Ihrem Projekt beizutragen. Verwenden Sie Tools wie Sphinx, um Dokumentation aus Ihrem Code zu generieren.
5. Verwenden Sie Continuous Integration (CI)
Richten Sie ein CI-System (z. B. GitHub Actions, Travis CI, GitLab CI) ein, um Ihr Paket automatisch zu erstellen, zu testen und bereitzustellen, wenn Änderungen an Ihrem Code vorgenommen werden. Dies trägt dazu bei, dass sich Ihr Paket immer in einem funktionierenden Zustand befindet.
Beispiel für die Konfiguration von GitHub Actions:
```yaml name: Python Package on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python 3.9 uses: actions/setup-python@v4 with: python-version: 3.9 - name: Install dependencies run: | python -m pip install --upgrade pip pip install poetry poetry install - name: Lint with flake8 run: | poetry run flake8 . - name: Test with pytest run: | poetry run pytest ```6. Veröffentlichen Sie Ihr Paket auf PyPI
Teilen Sie Ihr Paket mit der Welt, indem Sie es im Python Package Index (PyPI) veröffentlichen. Dies erleichtert es anderen, Ihr Paket zu installieren und zu verwenden.
Schritte zum Veröffentlichen auf PyPI:
- Registrieren Sie ein Konto auf PyPI und TestPyPI.
- Installieren Sie
twine:pip install twine. - Erstellen Sie Ihr Paket:
poetry buildoderpython setup.py sdist bdist_wheel. - Laden Sie Ihr Paket auf TestPyPI hoch:
twine upload --repository testpypi dist/*. - Laden Sie Ihr Paket auf PyPI hoch:
twine upload dist/*.
Beispiele aus der Praxis
Sehen wir uns an, wie einige beliebte Python-Projekte pyproject.toml verwenden:
- Poetry: Verwendet
pyproject.tomlfür sein eigenes Paketmanagement. - Black: Der kompromisslose Code-Formatter verwendet ebenfalls
pyproject.toml. - FastAPI: Ein modernes, schnelles (leistungsstarkes) Web-Framework für den Aufbau von APIs mit Python verwendet es ebenfalls.
Fazit
pyproject.toml stellt den modernen Standard für das Python-Paketmanagement dar und bietet eine deklarative und sichere Möglichkeit, Ihre Paketmetadaten zu definieren und Abhängigkeiten zu verwalten. Während setup.py uns gute Dienste geleistet hat, ist die Migration zu pyproject.toml eine lohnende Investition für langfristige Wartbarkeit, Konsistenz und die Integration mit modernen Werkzeugen. Durch die Übernahme von Best Practices und die Verwendung der richtigen Tools können Sie Ihren Python-Paketierungs-Workflow optimieren und qualitativ hochwertige, wiederverwendbare Pakete erstellen.